Excellent, thank you. There are so many good syntax fixes here!

The draft of the DRY looks like the right general direction.

I would like to try out some options during the next few days...

For example, my intuition is there may be some value to having the directory also contain a file that is ready to copy/paste into a user's own file, that has the alias keyword and definition, and also comments/documentation. This tends to make it really easy to share one alias with someone.

Could there be advantage to naming that file the same as the actual alias (e.g. "git-foo.txt") rather than a file name that is the same across all aliases? An advantage that comes to mind is making it easy for a user to download a few aliases, and be able to distinguish the downloaded files via the file names. Users have asked for this, for some of the more-complex aliases such as chart and churn.

Lots to think about. Thank you for motivating this!

Excellent, thank you. There are so many good syntax fixes here!

The syntax fixes are actually what's #106 is about. This is just ahead of #106 :)

For example, my intuition is there may be some value to having the directory also contain a file that is ready to copy/paste into a user's own file, that has the alias keyword and definition, and also comments/documentation. This tends to make it really easy to share one alias with someone.

Yeah, I also had this in mind.

Could there be advantage to naming that file the same as the actual alias (e.g. "git-foo.txt") rather than a file name that is the same across all aliases? An advantage that comes to mind is making it easy for a user to download a few aliases, and be able to distinguish the downloaded files via the file names. Users have asked for this, for some of the more-complex aliases such as chart and churn.

Some people seem to use .gitconfig as file extension, see a GitHub search for path:*/*.gitconfig. I think that's reasonable, and added generation of these files (for non-shell aliases) to the script. Of course, this would have to be extended to work with scripts, but I'd like wait until we agree on a layout before working on details like line breaks and escaping of shell aliases.

Lots to think about. Thank you for motivating this!

Great!

Your .gitconfig extension is a good addition IMHO. Big picture, I favor file extensions, because editors can pick up syntax highlighting and autocomplete more easily.

What do you think about putting the new *.gitconfig files into their directories?

Such as:

./doc/git-foo/git-foo.gitconfig

Upside is it makes directory navigation easier and cleaner. Downside is the URL is repetitive.

I slightly favor the upside, because it feels to me like the directory will be the one place someone will have to look. To me, this looks like helpful encapsulation.

Am I viewing it correctly that the big open question to solve is where the comments and examples go?

Am I viewing it correctly that the big open question to solve is where the comments and examples go?

I guess so. If I understand correctly we agree on the following:

1. Directory structure.
2. ${ALIAS_DIR}/alias.{sh,txt} files to define the alias.
3. Generation of ${ALIAS_DIR}/${ALIAS_NAME}.gitconfig from ${ALIAS_DIR}/alias.{txt,sh}.
4. Generation of ${ALIAS_DIR}/README.md. Details are unclear.

We still need to refine (4.).

I think that README.md could be generated from a template, e.g.:

# git ${ALIAS_NAME}

\```gitconfig
${ALIAS_NAME} = ${ALIAS_DEFINTION}
\```

${DESCRIPTION}

(Note that the backslash is only there since I am also writing this comment in markdown...)

In the simplest case, ${DESCRIPTION} is just the contents of some file, e.g. ${ALIAS_DIR}/description.md and it contains only headings ## and below, including examples. Now the question is whether this is sufficient. It could be, but maybe you have more requirements regarding special treatment of examples, comments, etc.?

Also note that we should be able to generate /gitalias.txt:

${DESCRIPTION} # here, the description must be prepended with `#` per line, to get a comment.
${ALIAS_NAME} = ${ALIAS_DEFINITION}

Is it sufficient to have the same description in README.md and in gitalias.txt? If not, how do the requirements differ? Do we just want to remove some lines from the description before appending contents to gitalias.txt?

Also, where do the "TODOs" go? I'd say temporarily into ${ALIAS_DIR}/todo.md, but ideally only GitHub issues and no TODOs.

One other thing I don't understand is why there is index.md and README.md. I guess README.md should be sufficient. If the generation process for the website requires index.md files that are identical to README.md anyway, the generation process could just cp, ln -s, or mv appropriately. It tends to confuse people...

Directory structure

Yes.

${ALIAS_DIR}/alias.{sh,txt} files to define the alias.

Yes. Open question of where to put corresponding documentation for comments, examples, credit, references, etc.?

Generation of ${ALIAS_DIR}/${ALIAS_NAME}.gitconfig from ${ALIAS_DIR}/alias.{txt,sh}.

Yes. Open question of documentation as above?

Generation of ${ALIAS_DIR}/README.md. Details are unclear.

Yes, except minor correction that the output file is index.md and the symlink README.md. This is because of limitations of some onsite (i.e. not GitHub) git hosting setups.

In the simplest case, ${DESCRIPTION} is just the contents of some file, e.g. ${ALIAS_DIR}/description.md

Yes. Perhaps the name alias.md so it corresponds to the others?

it contains only headings ## and below, including examples.

Yes that's good. I don't have any more requirements for the content for each specific alias. As you've seen, there are groups of related aliases, and currently I'm doing copy/paste for the content for these, e.g. "Related aliases" at the bottom of a markdown documentation page. Beyond this commit, it could be good to have a way to manage these.

Now the question is whether this is sufficient

Yes.

Also note that we should be able to generate /gitalias.txt:

Yes.

Is it sufficient to have the same description in README.md and in gitalias.txt?

Mostly yes.

The most-important difference is there are some chunks of the top-level file that are written to be easy for teams to discuss and adopt.

For example, there's currently an opening section of tiny shortcuts that are so simple that there is no per-alias comment. This opening section is what convinces the majority of teams to try the aliases. I.e. the file is deliberately organized to make it easy for teams to understand and adopt. In practice, this shortcut section is the #1 reason teams say yes to trying gitalias.

Also, where do the "TODOs" go? I'd say temporarily into ${ALIAS_DIR}/todo.md,

Yes.

but ideally only GitHub issues and no TODOs.

GitHub lock-in has been problematic in practice for some large customers.

A file todo.md has been a least-worst solution.

One other thing I don't understand is why there is index.md and README.md.

Yes, that's a workaround just for GitHub's problem.

The index.* file convention is to set the file that renders when a user visits the directory without specifying a file name. This has a bunch of advantages on non-GitHub systems.

Unfortunately, GitHub tooling renders the file README.md, but not the file index.md. GitHub doesn't yet (AFAIK) allow that file name to be customized.

This overall issue has a long history of causing errors in many projects, and with documentation systems, customer internal search engines, etc

Every year or so, I try to check to see if the situation has improved. My understanding is GitHub staff wants the file name README.md to represent what a developer should see first when diving into a directory using developer-oriented tooling (e.g. GitHub's typical directory browser) whereas the file name index.* to be what a typical webserver renders.

One workaround is a symlink. Another potential workaround is cp, but when I tried that, the files sometimes accidentally diverged. In my ideal world, GitHub management adds a rule to render README.md if it's available, and if not, renderindex.md; then I'd delete all the ./doc/**/README.md files.

Perhaps there are other approaches?

Directory structure

Yes.

${ALIAS_DIR}/alias.{sh,txt} files to define the alias.

Yes. Open question of where to put corresponding documentation for comments, examples, credit, references, etc.?

Sorry, but I am not sure I understand your question. Regular, i.e. non-shell, aliases do not allow comments as part of the alias. Shell-aliases do allow comments, like any other shell script.

General comments on the alias, examples, credit, references go in alias.md (using markdown and headings ## and lower), as you mention (see below).

Apart from that, there would be no place to add any additional information.

Generation of ${ALIAS_DIR}/${ALIAS_NAME}.gitconfig from ${ALIAS_DIR}/alias.{txt,sh}.

Yes. Open question of documentation as above?

Again, I do not understand exactly what you mean.

Generation of ${ALIAS_DIR}/README.md. Details are unclear.

Yes, except minor correction that the output file is index.md and the symlink README.md. This is because of limitations of some onsite (i.e. not GitHub) git hosting setups.

OK.

In the simplest case, ${DESCRIPTION} is just the contents of some file, e.g. ${ALIAS_DIR}/description.md

Yes. Perhaps the name alias.md so it corresponds to the others?

I like alias.md.

it contains only headings ## and below, including examples.

Yes that's good. I don't have any more requirements for the content for each specific alias.

alias.md is where the things you mentioned above (examples, credit, references) would have to go. Unless we're misunderstand each other, so I am just stating it once more.

As you've seen, there are groups of related aliases, and currently I'm doing copy/paste for the content for these, e.g. "Related aliases" at the bottom of a markdown documentation page. Beyond this commit, it could be good to have a way to manage these.

Right. Maybe we can use ${ALIAS_DIR}/related.txt which just contains a list of aliases (one line per) to automatically generate a "Related Aliases" section.

Is it sufficient to have the same description in README.md and in gitalias.txt?

Mostly yes.

The most-important difference is there are some chunks of the top-level file that are written to be easy for teams to discuss and adopt.

For example, there's currently an opening section of tiny shortcuts that are so simple that there is no per-alias comment. This opening section is what convinces the majority of teams to try the aliases. I.e. the file is deliberately organized to make it easy for teams to understand and adopt. In practice, this shortcut section is the #1 reason teams say yes to trying gitalias.

Right. Without adding any exceptions to our design so far, these very short aliases would have an empty alias.md (so that they are just placed on top of each other without separating them by comments that are generated from the content of alias.md).

When it comes to sorting, I'd say we can use tsort(1p). One file order.txt which would specify that we want to start with things like "a", "b", "c", "d", "f", ..., then a marker, and then any other topology we want, breaking ties lexicographically. We then generate gitalias.txt in the order of output from our tsort invocation.

[TODOs, GitHub lock-in]
A file todo.md has been a least-worst solution.

OK.

[index.md vs. README.md]

Alright. I do get that there are outside constraints, but to be honest I don't want to continue discussing it here and now. Absolutely no problem with the discussion per se, but I think just want to accept that README.md is a symlink to index.md which does not really affect our design, and resume the conversation once we're done with the current task.

I think I have enough information to prototype generation of */index.md and gitalias.txt. Stay tuned...

Yes. Open question of where to put corresponding documentation for comments, examples, credit, references, etc.?

Sorry, I was unclear.

What I'm imagiging is something like these pseudocode samples, that have a block comment with ilne 1 alias title (e.g. "git-foo"), line 3 as a one-line sentence summary (e.g. "Foo because bar."), then examples, discussion, etc.

File git-pr:

[alias]
# git-pr
#
# Pull with rebase in order to provide a cleaner, linear, bisectable history
#
# … Help and commentary as needed …
# … Some aliases have a bunch of help and discussion …
# … Various thanks, credits, reference links, etc. …
pr = pull --rebase

alias.md is where the things you mentioned above (examples, credit, references) would have to go. Unless we're misunderstand each other, so I am just stating it once more.

Yes good. We understand each other.

Right. Maybe we can use ${ALIAS_DIR}/related.txt which just contains a list of aliases (one line per) to automatically generate a "Related Aliases" section.

Good idea. Yes.

Right. Without adding any exceptions to our design so far, these very short aliases would have an empty alias.md (so that they are just placed on top of each other without separating them by comments that are generated from the content of alias.md).

Yes that makes sense to me.

When it comes to sorting, I'd say we can use tsort(1p).

One file order.txt which would specify that we want to start with things …

I'm unsure if I'm understanding you here. Are saying akin to a table-of-contents file and/or an ordered manifest file? This sounds fine to me.

The purpose is to ensure grouping of related aliases, such as the one-letter shorthands, the the log-related aliases, the topic branch aliases, the maintenance aliases such as optimize, etc.

For what it's worth, changes to alias ordering are extremely rare. The typical change is inserting one alias. The rare change is inserting a group of aliases, such as the new worktree aliases in progress in the other merge request.

to be honest I don't want to continue discussing it here and now.

I agree with you about this one. <3 Thank you for being understanding of the quirks! :-)